home *** CD-ROM | disk | FTP | other *** search
/ Pluspack 1 / Caligari Corporation Pluspack1 1998.iso / TSX_SDK / tsxINC / tsxLight.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-01-28  |  6.5 KB  |  191 lines
  1. //******************************************************************************
  2. //    File: tsxLight.h
  3. //  Module: trueSpace eXtensions API
  4. //   Descr: Interface to tsxLIGHT
  5. //******************************************************************************
  6.  
  7. #ifndef TSXLIGHT_H
  8. #define TSXLIGHT_H
  9.  
  10.  
  11. #include "tsxTypes.h"
  12.  
  13.  
  14. //------------------------------------------------------------------------------
  15. //------------------------------------------------------------------------------
  16.  
  17. // tsxLIGHT contains the following information in addition to tsxGNODE:
  18. //    - type
  19. //      - color
  20. //      - intensity
  21. //      - falloff
  22. //      - shadow properties
  23. //      - (Spot) cone angle, hot-spot ratio
  24. // Please consult the trueSpace Reference Manual for detailed description
  25. // of the shadow and other attributes.
  26. // The Z axis of a Spot or Infinite Light points in the direction of the
  27. // light rays.
  28.  
  29.  
  30. //------------------------------------------------------------------------------
  31. //    Related types and definitions
  32. //------------------------------------------------------------------------------
  33.  
  34. // Light types
  35. enum tsxLIGHT_TYPE {
  36.     e_tsxLT_UNDEF = 0,
  37.     e_tsxLT_INFINITE, //Light from an very distant source
  38.     e_tsxLT_LOCAL,    //Light from a local point source
  39.     e_tsxLT_SPOT        //A spot-light
  40. };
  41.  
  42. // Light intensity falloff
  43. enum tsxLIGHT_FALLOFF {
  44.     e_tsxLF_UNDEF = 0,
  45.     e_tsxLF_ZERO,    //No falloff
  46.     e_tsxLF_LINEAR,  //Linear with distance
  47.     e_tsxLF_SQUARED  //square of distance
  48. };
  49.  
  50. // Shadow type
  51. enum tsxLIGHT_SHADOWING {
  52.     e_tsxLS_NOSHADOWS = 0,
  53.     e_tsxLS_RAYTRACE,
  54.     e_tsxLS_SHADOWMAP
  55. };
  56.  
  57. // Shadow-map Size
  58. enum tsxLIGHT_SMSIZE {
  59.     e_tsxSMZ_UNDEF = 0,
  60.     e_tsxSMZ_LOW,
  61.     e_tsxSMZ_MEDIUM,
  62.     e_tsxSMZ_HIGH
  63. };
  64.  
  65. // Shadow-map sharpness
  66. enum tsxLIGHT_SMSHARPNESS {
  67.     e_tsxSMS_UNDEF = 0,
  68.     e_tsxSMS_LOW,
  69.     e_tsxSMS_MEDIUM,
  70.     e_tsxSMS_HIGH
  71. };
  72.  
  73.  
  74. //------------------------------------------------------------------------------
  75. //    Managers
  76. //------------------------------------------------------------------------------
  77.  
  78. // Creates a Light of specified LtType at world origin,
  79. // with default position, orientation and attributes.
  80. // On success, the new Light is the currently selected object.
  81. // Default location: Spot, Local -- (0,0,1), Infinite -- (0,0,0).
  82. // Default orientation: 180 deg rotation about world X, making it
  83. //  point towards world origin (spot, infinite) with its Z axis.
  84. //  The axes are aligned as follows:
  85. //    X aligned with World X,
  86. //    Y and Z aligned with world negative Y and negative Z.
  87. TSXAPIFN tsxERR tsxLightCreateInScene( tsxLIGHT_TYPE LtType );
  88.  
  89. // Use `tsxSobjDelete' to remove and delete from scene, and GNODE functions
  90. // to manage in the scene graph and access/modify position.
  91.  
  92.  
  93. //------------------------------------------------------------------------------
  94. //    Common Attributes
  95. //------------------------------------------------------------------------------
  96.  
  97. // Note: None of the following routines for modifying a light's attributes
  98. // update the display.
  99.  
  100. // Light type
  101. TSXAPIFN tsxLIGHT_TYPE tsxLightGetType( tsxLIGHT* pLight );
  102.  
  103. // Get Light color (copied into pColor).
  104. TSXAPIFN void tsxLightGetColor( tsxLIGHT* pLight, CtsxColor* pColor );
  105.  
  106. // Set Light color (copied from pColor).
  107. TSXAPIFN void tsxLightSetColor( tsxLIGHT* pLight, CtsxColor* pColor );
  108.  
  109. // Get the light intensity. Returns -1 if not a light.
  110. TSXAPIFN float tsxLightGetIntensity( tsxLIGHT* pLight );
  111.  
  112. // Set the light intensity. Returns new intensity, -1.0 if not a light.
  113. TSXAPIFN float tsxLightSetIntensity( tsxLIGHT* pLight, float fNewIntens );
  114.  
  115. // Get the light intensity falloff type with distance.
  116. TSXAPIFN tsxLIGHT_FALLOFF tsxLightGetFalloff( tsxLIGHT* pLight );
  117.  
  118. // Set the light intensity falloff type with distance.
  119. // Returns new value, or tsxLF_UNDEF for invalid request.
  120. TSXAPIFN tsxLIGHT_FALLOFF tsxLightSetFalloff( tsxLIGHT* pLight,
  121.                           tsxLIGHT_FALLOFF NewFo );
  122.  
  123. // Shadowing.
  124. TSXAPIFN tsxLIGHT_SHADOWING tsxLightGetShadType( tsxLIGHT* pLight );
  125.  
  126. // Set shadowing type.
  127. // Returns new value, e_tsxLS_NOSHADOWS if not a light.
  128. TSXAPIFN tsxLIGHT_SHADOWING tsxLightSetShadType(
  129.     tsxLIGHT* pLight,
  130.     tsxLIGHT_SHADOWING newShType
  131.     );
  132.  
  133. // True if shadow-map is image size dependent.
  134. TSXAPIFN tsxBOOL tsxLightIsShadImgDep( tsxLIGHT* pLight );
  135.  
  136. // (Un)Set shadow-map's image size dependence.
  137. // Returns new value, False if not a light.
  138. TSXAPIFN tsxBOOL tsxLightSetShadImgDep(
  139.     tsxLIGHT* pLight,
  140.     tsxBOOL bDependent //True to make it dependent
  141.     );
  142.  
  143. // Get shadow-map size
  144. TSXAPIFN tsxLIGHT_SMSIZE tsxLightGetShmapSize( tsxLIGHT* pLight );
  145.  
  146. // Set shadow-map size. Returns new value, or e_tsxSMZ_UNDEF if invalid request.
  147. TSXAPIFN tsxLIGHT_SMSIZE tsxLightSetShmapSize(
  148.     tsxLIGHT* pLight,
  149.     tsxLIGHT_SMSIZE NewSz
  150.     );
  151.  
  152. // Get shadow-map sharpness (_UNDEF if not light).
  153. TSXAPIFN tsxLIGHT_SMSHARPNESS tsxLightGetShmapSharpness( tsxLIGHT* pLight );
  154.  
  155. // Set shadow-map sharpness.
  156. // Returns new value, or tsxSMS_UNDEF for invalid request.
  157. TSXAPIFN tsxLIGHT_SMSHARPNESS tsxLightSetShmapSharpness(
  158.     tsxLIGHT* pLight,
  159.     tsxLIGHT_SMSHARPNESS NewSharpness
  160.     );
  161.  
  162.  
  163. //------------------------------------------------------------------------------
  164. //    Spotlight Attributes
  165. //------------------------------------------------------------------------------
  166.  
  167. // Get cone angle (in radians).
  168. // This is the solid angle of the lit area subtended at the light source.
  169. // Returns -1.0 if not a spotlight.
  170. TSXAPIFN float tsxLightGetSpotAngle( tsxLIGHT* pLight );
  171.  
  172. // Set the spotlight cone angle (in radians).
  173. // Returns the new angle, -1 if not a spotlight.
  174. TSXAPIFN float tsxLightSetSpotAngle( tsxLIGHT* pLight, float newAngle );
  175.  
  176. // Get the hot-spot ratio.
  177. // The hot-spot in a spotlight is the inner circle of even bright light.
  178. // In the lit ring outside the hot-spot, the light intensity decreases
  179. // towards the outer edge. The hot-spot ratio is the ratio of the hot-spot
  180. // cone solid angle to the entire spotlight cone solid angle.
  181. // Returns 0.0 <= ratio <= 1.0, -1.0 if not a light.
  182. TSXAPIFN float tsxLightGetSpotRatio( tsxLIGHT* pLight );
  183.  
  184. // Set the hot-spot ratio (see `tsxLightGetSpotRatio').
  185. // Returns new value, -1.0 if not a light, or invalid newRatio.
  186. TSXAPIFN float tsxLightSetSpotRatio( tsxLIGHT* pLight, float newRatio );
  187.  
  188.  
  189. //******************************************************************************
  190. #endif // TSXLIGHT_H
  191.